package com.jade.bss.customer.grant;

import java.security.Principal;
import java.util.List;

import com.jade.bss.customer.CustomerException;
import com.jade.bss.customer.permission.PermissionEntry;
import com.jade.bss.customer.role.RoleEntry;

/**
 * 授权管理器.提供对身份的授权操作(即身份与权限的关联关系).
 * 一个权限可以属于多个身份，一个身份可以拥有多个权限.
 *
 * @author sky
 * @version 1.0 13-4-18 上午9:42
 */
public interface GrantManager
{
    /**
     * 根据身份信息{@link Principal}来获取该身份所拥有的所有权限。
     *
     * @param principal 身份
     * @return 权限Entry列表
     */
    public List<PermissionEntry> getPermissions(Principal principal);

    /**
     * 根据一组身份信息来获取该身份所拥有的所有权限。
     *
     * @param principals 身份集合
     * @return 权限Entry列表
     * @throws CustomerException 操作异常
     */
    public List<PermissionEntry> getPermissions(Principal[] principals);

    /**
     * 设置指定身份的权限{@link Principal}.
     *
     * @param principal     身份.
     * @param permissionIds 权限ID集合.
     * @throws CustomerException 操作异常
     */
    public void setPermissions(Principal principal, int[] permissionIds)
            throws CustomerException;

    /**
     * 授予权限给身份{@link Principal}.
     *
     * @param principal    身份.
     * @param permissionId 权限ID.
     * @throws CustomerException 操作异常
     */
    public void grantPermission(Principal principal, int permissionId)
            throws CustomerException;

    /**
     * 授予权限给身份{@link Principal}.
     *
     * @param principal     身份.
     * @param permissionIds 权限ID集合.
     * @throws CustomerException 操作异常
     */
    public void grantPermissions(Principal principal, int[] permissionIds)
            throws CustomerException;

    /**
     * 授予权限给身份{@link Principal}.
     *
     * @param principal  身份.
     * @param permission 权限.
     * @throws CustomerException 操作异常
     */
    public void grantPermission(Principal principal, PermissionEntry permission)
            throws CustomerException;

    /**
     * Returns the list of the roles that the given principal has.
     *
     * @param principal the princal entity.
     * @return the list of the roles
     * @throws CustomerException if the operation can't be completed because some reasons, such as database error.
     */
    public List<RoleEntry> getRole(Principal principal)
            throws CustomerException;

    /**
     * 撤销一个身份拥有的所有权限.
     *
     * @param principal 身份信息.
     * @throws CustomerException 操作异常
     */
    public void revokePermissions(Principal principal)
            throws CustomerException;

    /**
     * 撤销身份{@link Principal}的权限..
     *
     * @param principal    身份.
     * @param permissionId 权限ID.
     * @throws CustomerException 操作异常
     */
    public void revokePermission(Principal principal, int permissionId)
            throws CustomerException;

    /**
     * 撤销身份{@link Principal}的一组权限{@link java.security.Permissions}.
     *
     * @param principal     身份.
     * @param permissionIds 权限ID集合{@link java.security.Permissions}.
     * @throws CustomerException 操作异常
     */
    public void revokePermissions(Principal principal, int[] permissionIds)
            throws CustomerException;

    /**
     * get principal entity list by role.
     *
     * @param roleId roleId
     * @return principal entity list
     */
    public List<Principal> listPrincipal(int roleId);

    /**
     * Adds the given role into the list of the roles that belongs to the given principal.
     * It menas that the principal has the all permissions that the role has.
     *
     * @param principal the principal entity
     * @param roleId    the role's ID
     * @throws CustomerException if the role is not existed or some reasons that cause the operation can't be
     *                        completed, such as database error.
     */
    public void grantRole(Principal principal, int roleId)
            throws CustomerException;

    /**
     * Adds an array of roles into the list of the roles that belongs to the given principal.
     * It menas that the principal has the all permissions that these roles have.
     *
     * @param principal the principal entity
     * @param roleIds   the array of IDs.
     * @throws CustomerException if the operation can't be completed because some reasons, such as database error.
     */
    public void grantRoles(Principal principal, int[] roleIds)
            throws CustomerException;

    /**
     * Set the principal's role..
     * It menas that the principal has the all permissions that the role has.
     *
     * @param principal the principal entity
     * @param roleIds   the role's ID
     * @throws CustomerException if the role is not existed or some reasons that cause the operation can't be
     *                        completed, such as database error.
     */
    public void setRoles(Principal principal, int[] roleIds)
            throws CustomerException;

    /**
     * Removes the given role from the list of the roles that belongs to the given principal.
     *
     * @param principal the principal entity.
     * @param roleId    the role's ID
     * @throws CustomerException if the operation can't be completed because some reasons, such as database error.
     */
    public void revokeRole(Principal principal, int roleId)
            throws CustomerException;

    /**
     * Removes an array of roles from the list of the roles that belongs to the given principal.
     *
     * @param principal principal entity.
     * @param roleIds   the array of IDs.
     * @throws CustomerException if the operation can't be completed because some reasons, such as database error.
     */
    public void revokeRoles(Principal principal, int[] roleIds)
            throws CustomerException;

    /**
     * Removes all roles that the given principal owns.
     *
     * @param principal the principal entity
     * @throws CustomerException if the operation can't be completed because some reasons, such as database error.
     */
    public void revokeRoles(Principal principal)
            throws CustomerException;

    /**
     * Removes all principals that the given role.
     *
     * @param roleId the role's id
     * @throws CustomerException if the operation can't be completed because some reasons, such as database error.
     */
    public void revokePrincipals(int roleId)
            throws CustomerException;
}
